Cream of the Crop 12/Cream of the Crop 12 (Part II)/Cream of the Crop 12 (Part II).iso/BBS/LL_100.ZIP/LOGLIST.DOC

Text File | 1996-01-21 | 20.0 KB | 555 lines

                            TBBS Log-Lister

                             by Paul Blitz

                             Version 1.00
                               20 Jan 96


Introduction
============

Last year, I wrote some simple programs to list out certain (fixed) fields
from the userlog to a text file. Michael Muller suggested that a more
complete & more flexible program would be useful, especially so that the
output files could be used with TYPE 1 & 2 text listing commands.

Log-Lister allows you to create your own customised lists from your TBBS
userlog file. These files list one user's details per line, and may include
colourisation commands (using "%Xnn%" sequences), fixed text, headings,
tabs, as well as the data itself.

The "definition" of the output is made in the configuration file: you can
have several of these, and simply call up the one you want to use on the
program's command line.

Log-Lister is a DOS program, and would typically be called as part of your
night-time external event, from the relevant batch file (that's YOUR
problem, not mine... <grin>)

This version of Log Lister has been written for use with TBBS 2.3.


Future Versions
===============

I hope that there will be enough interest to make it worthwhile improving
the program further.... if you have any suggestions for improvements to
the program, then let me know (see the end for contact addresses)

When you register, your "registration key" will be valid for all future
"non-major" upgrades to the program.


Running the program
===================

LOGLIST.EXE and your TBBS userlog (USERLOG.BBS) do *not* need to be
together in the same directory, as long as you define a full path to your
userlog. Unless Borland have screwed up the pascal compiler, your userlog
is only ever opened for READING, so your userlog won't be disturbed in any
way.

The program calling syntax is:

    LOGLIST <config file>

If you don't give a config file, then "LOGLIST.CFG", in the current
directory, will be used.

The filename may include a full pathname, upto a maximum length of 50
characters.

The config file not only contains formatting information, but gives the
paths & filenames for the USERLOG.BBS file, the output text file, and the
log file. This allows you to have multiple configuration files to produce
several output files.


The program will return one of several error levels when it exits:

    0 : Program ran OK
    1 : Error in command line parameters
    2 : Can't find file
    3 : Error in config file
    9 : Control-C / Escape was pressed during program
    99: Internal processing error (eg: out of range value)

All errors will also return an error message on the screen (and the log
file), with as much useful information as possible.

To help get you going, I've included some demo config files... if *you* do
any good configs, please send them to me, and I'll include them (and then
you could become famous!!)


How it works
============

The program simply creates a textual list file, which can either be
printed, or can be viewed online by your callers (eg with a TYPE1). The
file contains page headers, and one line of text for each user in your
userlog..... or rather for each user who matches the "restriction criteria"
(see below).

You can define a "page length": when you do this, the program will insert a
"%MORE%" at the relevant places. When viewed online, the user will then see
the data a page at a time.

The file can have a set of file- and page-header lines, and a set of
page-bottom lines: these are copied from the config file verbatim, so may
contain "real-time" substitution parameters which TBBS will expand for you.

The lines of user data are then built up from lines of different types of
data (eg words, substitution parameters and colourisation commands). If the
data contains substitution parameters, then they are replaced by the
relevant data from the userlog records.

For example, the set of data might include:

  header "A list of names etc"
  header "-------------------"
  %X03%
  %NAME%
  Tab to column 20
  %X95%
  %PHONE%
  Tab to column 35
  %X22%
  %ADDR1%
  a ","
  a space
  %ADDR2%
  a "."

(this is NOT actually how the data is defined... see below)

This would give a list something like this:

A list of names etc
-------------------
Paul Blitz         %X95%441962885696   %X22%25 Woodgreen Road, Winchester.
Phil Becker        %X95%303 699 6565   %X22%15200 E. Girard Ave., Aurora.
.... etc

The "file header" gets printed once, at the top of the file. The "page
headers" are printed at the top of the second and subsequent pages (after a
"%MORE%").

The way the data is created is defined by the config file (see below). If
you want to create several lists, then you simply create multiple
configuration files, and run LOGLIST multiple times, specifying the
different config files.



Config File format
==================

The config file format is, I hope, fairly straight-forward, and if best
understood by looking at the supplied demo config files.

Column 1 of the file defines what that line is:

  U or u  - path & filename of your USERLOG.BBS file
  O or o  - path & filename of the output file
  L or l  - path & filename of the log file
  F or f  - a file header line
  P or p  - a page header line
  B or b  - a page bottom line
  R or r  - restriction criteria
  D or d  - a data field
  S or s  - a space setting
  T or t  - a tab setting
  M or m  - lines after which to insert a "%MORE%"
  X or x  - special options

Anything else in column 1 will cause the rest of the line to be ignored:
this is a good way of adding comments. To cover future expansion, I'd
advise using a ";", as that will be reserved for comments in all future
versions for comment lines (anything else could get used for something!)

Column 2 onwards holds the data. The line of data is ended by a <cr>
(chr(13)). To make things predictable, all TRAILING spaces are removed (use
the "S" or "T" command to include spaces at the end of the data)

Apart from the headers and comments, you may have upto 200 "items". These
will display in the order they appear in the config file.


Userlog, Output and Log files:
------------------------------
These three line types define where your userlog, output, and error log
files are. If you are silly enough to duplicate either of these, then the
last one will be used. Each path/filename may be upto 50 characters long.

If the userlog file can not be found, the program will abort.

The output file will simply overwrite any existing file.

The log file will simply append to any existing file: at a minimum, the log
will list the date / time of the run, and the config files used. The log
file is not opened until the config file has been read (as that is where
the error log's name is defined), so errors in the config file which cause
a program abort will not be logged (if this becomes a big problem, let me
know, and I'll work out a way around it).

You would normally put these as the first three lines of your config file.


File Header lines:
------------------
You can have up to 10 file header lines, each limited to being 120
characters long. They are simply copied verbatim to the beginning of the
output file in the order they appear in the config file.

Whilst they need not be in a block at the top of the file, you'll probably
find it easier if they are!

You can include ANY substitution parameters you like: as they will be
copied verbatim, they will be "expanded" when the output file is displayed
by TBBS. This could be a nice place to put a "clear-screen" or to put the
time / date.


Page Header lines:
------------------
This text gets put at the top of every *new* page... in other words, it is
the line or lines of text that follow the %MORE% command. It does NOT get
put at the top of the first page, so you'll need to specifically duplicate
any text you want in the HEADER fields.

As the program is simple, you COULD end up with just the page heading on
the last page!

You might want to include a "clear screen" in this.... if so, put it on the
first line (pretty obvious, I realise), as there is no special handling of
page length (for the %more% insertion) if you DO include the clear-screen.

You can include what you like in these lines: it is interpreted just like
the File Header lines. You may have up to 5 of these lines, each of up to
120 chars.


Page Bottom lines:
------------------
This text gets put at the bottom of every page... in other words, it is
the line or lines of text that immediately precede the %MORE% command. You
might want to use this for a dashed line, or maybe to insert a special
message.

You can include what you like in these lines: it is interpreted just like
the File/Page Header lines. You may have up to 5 of these lines, each of up
to 120 chars.


Restriction Criteria
--------------------
The restriction criteria allows you to output just a selected subset of
your userlog, based on specified user settings (eg priv level, A flags...)

If you don't specify any restrictions, ALL entries in the userlog will be
listed.

There are two types of "matching" in the restrictions, numerical value, and
flag(s):

a) Numerical value
   The format of this command is "r[name]['>' or '=' or '<'][0-255]". For
 example, to list users whose priv is under 100 you would use "rpriv<100".

b) Flag(s)
   The format of this command is "r[name]=[flag(s)]". Where [flags(s)] are
 either 'X' (or 'x', = set) or '.' (= reset) or '-' (don't care).
   Depending on the actual command, there may only be a single flag (eg
 "rinvisible=X") or 8 flags (eg "rA1=XXXX....").
   Note that *ALL* bits of the flag must be defined (ie all 8 for an
 a-flag).

If you duplicate a restriction type (eg two "RPRIV" lines) the last one
only will be used.

If more than one (different) restriction is specified, then ALL conditions
must be met for inclusion on the listing.

A full list of the supported restriction fields will be found in
"_RESTRIC.TXT"



Data fields:
------------
Visible fields can contain fixed data (eg "Name: "), substituted data (eg
"%FIRST%", or colourisation data (eg "%X0F%"). The program ignores the
"size" of any %Xnn% colourisation commands (as they are not actually
displayed), so that tab parameters etc will be in the correct locations
when displayed online (as an added bonus, any %Xnn% colourisation commands
within the user data will also be respected).

The substitution codes supported are generally the same as those listed in
the TBBS 2.3 manual / TBBS 2.3 ULEDIT.DOC file. However, certain fields,
don't really make sense (eg %TIME%) in a list like this, so they are not
included.

(my TBBS manual shows the full list on pages 2-15 thru 2-17)

You may include spaces within the string of data, but all trailing spaces
will be removed (that way things are 100% predictable, and you won't get
caught out!)

Each data field definition is limited to 50 characters: if you need a
longer field, use multiple fields!

Note: whilst you can include escape sequences in the data fields, this
program will treat them like normal "visible" data: this means that not
only will they will (wrongly) count towards the line length (making tab
positions incorrect), they will also be deleted - perhaps only partially -
when truncating a line for tabbing. I therefore suggest that you DO NOT USE
ANSI ESCAPE SEQUENCES, but use the %Xnn% sequences instead.

A full list of the supported substitution codes will be found in
"_PARAMS.TXT"


Space fields:
-------------
Just follow the "s" by the number of spaces you want... as data fields
can't have any trailing spaces, you can use this to add them!

Valid range is 1 to 255.


Tab fields:
-----------
Follow the "t" by the desired column. The way this works is that the
"string so far" will be trimmed, and spacea added as needed, so that the
next character will be in the specified column.

If you want to make the trimmed data have a space before the next data,
then either use another "tab" field, or a "space" field straight after.

(eg: data so far on the line fills 43 chars. You wish to truncate this to
30 with a"t30" command: if you do that, there will be no space between the
existing data, and the new field at the 30th column. To get a space in
column 29 [so that there is a definte column break], tab to 29, then either
now tab to 30, or insert a single space)

Tab fields will safely ignore any %Xnn% fields when it truncates lines.

Valid range is 1 to 255.


More field:
-----------
Rather than the list being one long list, you might prefer to automatically
insert a "%MORE%" every X lines... the number following the "m" is the
number of "lines per screen" you want displaying.... so if you make this =
23, then the %MORE% will appear on the 23rd line.

The "page bottoms" are inserted prior to this line, and "page header" lines
are added after this line.

Valid range is 1 to 255.


Special Options
---------------
This is my way of picking up any odd things. The second character defines
WHICH special option it is.

"X1" defines the two characters used to replace the starting & ending "%"
signs on any %xxxx% fields (not including %Xnn%, which are not affected)
found in the userlog data - for example, some sysops use the location field
for a user's "tag-line", which can contain things like "%Location%".

If we left these as they are, then they would be substituted at run-time,
and we would find that our lovely tabs are all wrong!

To get around this, Log Lister simply changes the % signs! A setting of
"X1<>" would make a "%location%" in a user's data become "<location>".

If you WANT to leave the "%" symbols there, then just use "X1%%".......


Other Special Options may be defined in the future.


Other
-----
The overall line length of the output data is limited to 255 characters. If
it gets longer, then it will simply truncate.



%zzzzz% Field Formatting
========================

Log Lister allows you to optionally include field formatting information in
the %zzzzz% commands used on data lines. The syntax is (I hope) exactly the
same as used in the ULEDIT printing template files.

Normally, a parameter looks like %zzzzz% (eg %NAME%), which will simply add
that data to the print-line.

However, by adding in a ":" followed by further information, you can (a)
set the length of that printed data (which either trims it, or pads it
out); (b) left or right justify the data; (c) choose whether to use either
spaces or zeros to pad the data.

The syntax is quite simple:

    %zzzzz[:[+|-]nnn[U|L|C]]%

where:  zzzzz is the "substitution" code
        nnn   is a numerical value, range 1 to 255.

The formatting information starts with the ":". This may then be followed
by nnn to define the string size (eg ":25"): this will either TRIM the data
to nnn chars (if > nnn chars), or will LEFT justify the data in a nnn
character string. This is also equivalent to prefixing the string size with
a "-" (eg ":-25").

If you prefix the string size with a "+" (eg "+25"), then the data will be
RIGHT justified.

(If you don't include a number, then the field will be left the same size
as it was)

Normally, the resulting string will be padded with spaces (great for
textual fields), but if you start nnn with a "0" (eg "017" instead of just
"17"), then the string gets padded with "0"s instead (great for numerical
fields).

If you end the formatting with U, L or C, then that will change the "case"
of the text. "U" will give you the data in *UPPER CASE*, "L" will give you
*lower case*, whilst "C" will give you *Mixed Case*.

Let's look at a few of examples... we'll assume that %NAME% is "PAUL
BLITZ", and that %BYTES24% is 12345:

                              123456789012345    <<<--- ruler
           %NAME:+15C%    is "     Paul Blitz"
           %NAME:-15L%    is "paul blitz     "
           %NAME:C%       is "Paul Blitz"
           %BYTES24:+07%  is "0012345"
           %BYTES24:-7%   is "12345  "
silly examples:
           %NAME:+015U%   is "00000PAUL BLITZ"
           %BYTES24:-07%  is "1234500"


The formatting commands can be used with ANY visible %xxx% substitution,
and will override any case-specifics that the %xxx% may otherwise have.

Watch out for unexpected things.... flag fields, normally "X..XXX..." will
become "x..xxx...".


Thanks...
=========

Thanks to lots of people:

.... to Michael Muller for coming up with the original idea (which expanded
a bit from his original ideas!), and for beta testing the program. Also to
Robert Gagliano, who also beta tested.

.... to the eSoft crew for not only creating TBBS, but for answering a few
questions along the way to help me write the program.

.... to Scott Sturgis at Zone One for distributing the program in the US,
and giving encouragement (and maybe some $$$ if you all register!!)

.... to Borland for creating Turbo Pascal (version 4) which all my programs
are written in.

.... to my family, who allow me to sit in my "computer room" writing email
to all you strange people in the US (I met many of you at ONEBBSCON '95, so
I KNOW how strange you are<g>), as well as programming.

.... to God, for creating me, and giving me the skills he has done!


Demonstration Version
=====================

This DEMONSTRATION VERSION of the Log Lister program is a fully functional
program, with *two* single exceptions: First, this version of the program
will only print out from the first 30 records of your TBBS userlog (your
listing may contain fewer lines of output if you use the restriction
commands). That should be more than enough to let you decide whether the
fully registered version of the program will be of use to you. Second, the
top of your output file will have a "nag line" or three added.... even more
reason to buy the proper program!

See below for how to buy the full version.


Copyright etc:
==============

This program is the copyright of Paul Blitz, 1995/6.

This demonstration version of the program may be freely used to help you
decide whether the full version will be of use to you. It may be freely
distributed, by any means (including via a BBS, on a CD etc) to all others,
on the simple condition that ALL files included in this archive are
included. Feel free to re-archive it using a different archiver.

Whilst I believe that this program works correctly, I do not GUARANTEE it.
All that I WILL guarantee is that it will take up space on your disk drive,
and that running the program may well cause it's output to take up even
more space!

It is up to *you* to decide that the program does what you want: I can not
be held responsible for any damage caused by this program to your computer,
the files on your computer, NOR for any other "knock-on" effects / damage
caused (eg loss of business), etc.

*************************************************************************
The FULL version of this product may NOT be copied, other than for taking
suitable security backups.
*************************************************************************


Purchasing the fully-working version
====================================


The fully registered version of LOGLIST is available exclusively from:


Paul Blitz,                            [e-mail]
25, Woodgreen Road,
Harestock,
Winchester,
Hants,
SO22 6LZ.

OR

zone one                               [e-mail]
8424A Santa Monica Blvd #200
West Hollywood, CA. 90069

Vox: 213.653.6450


(Please refer to the BUY_ME.TXT file for pricing details.)


If you have any bright suggestions, then feel free to write to me, or
contact me by phone at home (between 20:00 and 22:00 (UK time) ONLY please)
on [phone].

You may call my BBS: "The Cardboard Box BBS" on [phone] (for those
of you in the UK, who don't understand international dialling, call 01962
880278).

You can send email to me at Fidonet 2:252/201, Chatnet 44:2520/201, or
Internet "[e-mail]", or on the eSoft BBS.